Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Using Shape Objects

Manipulating Shape Object Properties

This section describes how to manipulate the properties of shape objects, including those that are references to other objects. In most cases, a pair of functions respectively get and set a property. You call the GXGetShapeProperty function to get a copy of the shape property you need; you call the GXSetShapeProperty function to assign a value to a property.

For manipulating shape objects as a whole, see "Creating and Manipulating Shape Objects" beginning on page 2-22.

Getting and Setting a Shape Object's Type, Fill, and Attributes

The functions described in this section get and set shape properties that are numerical values.

You can use the GXGetShapeType function to find the shape type of an existing shape, and the GXSetShapeType function to convert an existing shape from one shape type
to another. The section "Converting Shapes From One Type to Another" beginning on page 2-32 summarizes the kinds of shape conversions QuickDraw GX supports. Beyond that section and the descriptions in Table 2-1 on page 2-9, this book does not discuss specific shape types. See Inside Macintosh: QuickDraw GX Typography for more information on the typographic shape types--text, glyph, and layout. (Note that GXSetShapeType even allows you to convert typographic shapes to graphic shapes
of certain types.) See Inside Macintosh: QuickDraw GX Graphics for more information on graphic shape types.

The following code fragment determines the number of items (numParts) in a picture shape (theShape). The code uses GXGetShapeType to screen out any shape that is not a picture shape:

typeOfShape = GXGetShapeType(theShape);
if (typeOfShape == gxPictureType)
   numParts = GXGetPicture(theShape, nil, nil, nil, nil);

You can use the GXGetShapeFill function to find the fill of an existing shape, and the GXSetShapeFill function to set the fill of a shape when you create or modify it. Beyond the descriptions in Table 2-2 on page 2-13, this book does not discuss specific shape fills. See Inside Macintosh: QuickDraw GX Typography and Inside Macintosh: QuickDraw GX Graphics for more information on the valid typographic and graphic shape fills.

You can use the GXGetShapeAttributes function to find the attributes of an existing shape and the GXSetShapeAttributes function to set the attributes of a shape. Shape attributes are described in the section "Shape Attributes" beginning on page 2-16.

The following code fragment is a drawing loop that rotates a text shape (theText) six times around the point (x, y) by 15 degrees each time, and adds the shape to a picture (gthePage) after each rotation. (It also changes the color at each rotation, for better visibility of the overlapping text.) The loop sets the gxMapTransformShape attribute of the shape, which assures that the shape geometry itself is not affected by the rotation, and thus there is no loss of precision in the geometry with repeated rotations:

GXSetShapeAttributes(theText, gxMapTransformShape);
for (loop = 0; loop < 6; loop++) 
{
   GXSetShapeColor(theText, &textColor);
   GXRotateShape(theText, ff(15), x, y);
   GXSetPictureParts(gthePage, 0, 0, 1, &theText, nil, nil, nil);
   textColor.element.hsv.hue += 0x0940;
}

Note that the gxUniqueItemsShape attribute of gthePage must be set for this to work.

You can use GXGetShapeAttributes in combination with the GXSetShapeAttributes function to set and clear single attribute flags. For example, to clear the gxDiskShape attribute of a shape referenced by the variable target, you could use the following code:

GXSetShapeAttributes(target, 
                  GXGetShapeAttributes(target) & ~gxDiskShape);

Conversely, to set the gxDiskShape attribute, you could use the following code:

GXSetShapeAttributes(target, 
                  GXGetShapeAttributes(target) | gxDiskShape);

The GXGetShapeType function is described on page 2-66. The GXSetShapeType function is described on page 2-66. The GXGetShapeFill function is described
on page 2-68. The GXSetShapeFill function is described on page 2-69.
The GXGetShapeAttributes function is described on page 2-74. The GXSetShapeAttributes function is described on page 2-74.

Copying the Geometry From One Shape to Another

Like type, fill, and attributes, geometry is a property of a shape object. However, you access and manipulate a shape's geometry somewhat differently from other properties.

The GXSetShapeGeometry function copies the geometry (and the shape type, if
the shapes are of different types) from one shape object into another. To make the function call requires two object references, and no reference to or specification of
either object's geometry. There is no associated GXGetShapeGeometry call. Using GXSetShapeGeometry is a simple way to reuse an existing shape by turning it into
a copy of another shape. As with GXSetShapeType, this book does not discuss the specific rules for and consequences of converting one shape type to another with GXSetShapeGeometry. See Inside Macintosh: QuickDraw GX Graphics and Inside Macintosh: QuickDraw GX Typography for conversion information for graphic and typographic shape types.

To do more than simply copy geometries--to gain access to and actually manipulate
the contents of a shape's geometry--requires another set of functions, including the GXGetShapeStructure function. See the section "Directly Manipulating a Shape's Geometry" beginning on page 2-34. In most situations, however, you use functions specific to a given shape type to manipulate that type of shape's geometry. Those
kinds of functions are described, along with each shape type, in Inside Macintosh: QuickDraw GX Graphics and Inside Macintosh: QuickDraw GX Typography.

To copy an entire object, rather than just its geometry, you can use the GXCopyToShape or GXCopyDeepToShape functions; see "Copying, Comparing, and Cloning Shape Objects" on page 2-25.

The GXSetShapeGeometry function is described on page 2-67.

Getting and Setting a Shape Object's Style, Ink, and Transform

Every QuickDraw GX shape object has an associated style object, ink object, and transform object. You can use the GXGetShapeStyle, GXGetShapeInk, and GXGetShapeTransform functions to determine which of each type of object is referenced by a particular shape. Conversely, you can use the GXSetShapeStyle, GXSetShapeInk, and GXSetShapeTransform functions to change these references.

Because style objects can be shared among different QuickDraw GX shapes, the GXGetShapeStyle function can return a reference to the same style object for two different shapes. Likewise, the GXGetShapeInk and GXGetShapeTransform functions can return identical ink objects or transform objects for different shapes.

Calling GXSetShapeStyle, GXSetShapeInk, or GXSetShapeTransform increments the owner count of the specified style, ink, or transform object by 1, and disposes of the previously assigned style, ink, or transform. In certain cases, depending on how you create such an object or assign it to a shape, you may need to modify that object's owner count explicitly; see "Manipulating a Shape Object's Owner Count" on page 2-31.

The following code fragment draws a dashed version of a shape. The code first calls GXGetShapeStyle to obtain the style object attached to the shape theShape; it then clones the style and assigns a temporary reference (saveStyle) to the style. The code then assigns different style properties to the shape and draws it. After drawing the shape, the code restores the original style to the shape, using GXSetShapeStyle:

saveStyle = GXCloneStyle(GXGetShapeStyle(theShape));
GXSetShapePen(theShape, ff(1));
GXSetShapeDash(theShape, &dash);
GXDrawShape(theShape);

GXSetShapeStyle(theShape, saveStyle);
GXDisposeStyle(saveStyle);

As usual, after it is finished with the temporary reference saveStyle, the code disposes of it. For more information and examples of cloning, see for example the discussions of owner count in the chapter "Style Objects" in this book.

The GXGetShapeStyle function is described on page 2-69; the GXSetShapeStyle function is described on page 2-70. The GXGetShapeInk function is described on page 2-71; the GXSetShapeInk function is described on page 2-71. The GXGetShapeTransform function is described on page 2-72; the GXSetShapeTransform function is described on page 2-73.

Resetting a Shape Object's Properties to Their Default Values

When you create a new shape with the GXNewShape function, QuickDraw GX creates the new shape object by copying the appropriate default shape object. QuickDraw GX does not create a new style, ink, or transform object for the new shape, however. Instead, the new shape contains references to the same style, ink, and transform as the corresponding default shape. You are free to install a new style, ink, or transform in
the shape using functions such as GXSetShapeStyle, GXSetShapeInk, and GXSetShapeTransform.

If you do install a new style, ink, or transform in a shape and you want to revert back to the default style, ink, and transform, you can use the GXResetShape function. This function also resets the shape's attributes and fill properties to match the default shape, but does not alter the shape's geometry, owner count, or tag list.

The GXResetShape function is described on page 2-75.

Manipulating a Shape Object's Owner Count

The owner count of an object indicates the number of current references to that object. In general, QuickDraw GX manages owner counts for you. For example, when you create a new shape object you give it a variable name such as myShape. QuickDraw GX sets the owner count of the new shape to 1, because your application variable is the only current reference to the shape. As another example, when you add a shape to a picture, QuickDraw GX increments the shape's owner count, corresponding to the new reference to the shape contained in the picture.

The following code fragment is part of a routine that constructs a house image (gOurHouse) as a picture shape, building it out of individual geometric shapes. As each component shape (houseBorderShape and doorShape, in this fragment) is added to the picture shape, its owner count is increased; to balance that increase, and because that component shape's reference is no longer needed, it is disposed of.

GXSetShapeFill(houseBorderShape, gxHollowFill);
GXSetPictureParts(gOurHouse, 1, 0, 1, houseBorderShape, 
                  nil, nil, nil);
GXDisposeShape(houseBorderShape);

GXSetShapeFill(doorShape, gxHollowFill);
GXSetPictureParts(gOurHouse, 1, 0, 1, doorShape, 
                  nil, nil, nil);
GXDisposeShape(doorShape);

If you want to manage a shape's owner count directly--for example, if you want to track object references that you place in your own data structures, or if you want to know whether a shape object is shared--you can use the GXGetShapeOwners function to determine the owner count of a shape, and the GXCloneShape and GXDisposeShape functions to change the owner count of a shape. The GXCloneShape function increments the shape's owner count, and the GXDisposeShape function decrements the shape's owner count, freeing the memory used by the shape if the owner count goes to 0.

The GXGetShapeOwners function is described on page 2-76. The GXCloneShape function is described on page 2-61.The GXDisposeShape function is described on page 2-55.

Getting and Setting a Shape Object's Tag References

You can examine the list of references to tag objects currently associated with a shape using the GXGetShapeTags function. Once you create a tag object, you can attach it to a shape object using the GXSetShapeTags function. You can attach as many tag objects as you like to a shape object.

Tag objects and the basic functions for manipulating them are described in the chapter "Tag Objects" in this book. That chapter also lists the common tag types defined and reserved by Apple Computer, Inc.

The GXGetShapeTags function is described on page 2-77. The GXSetShapeTags function is described on page 2-78.